<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Allocators</title>
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../boost_asio.html" title="Boost.Asio">
<link rel="up" href="../model.html" title="Asynchronous Model">
<link rel="prev" href="executors.html" title="Executors">
<link rel="next" href="cancellation.html" title="Cancellation">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
<td align="center"><a href="../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="executors.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../model.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="cancellation.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_asio.overview.model.allocators"></a><a class="link" href="allocators.html" title="Allocators">Allocators</a>
</h4></div></div></div>
<p>
          Every asynchronous agent has an associated <span class="emphasis"><em>allocator</em></span>.
          An agent's allocator is an interface used by the agent's asynchronous operations
          to obtain <span class="emphasis"><em>per-operation stable memory</em></span> resources (POSMs).
          This name reflects the fact that the memory is per-operation because the
          memory is only retained for the lifetime of that operation, and stable,
          because the memory is guaranteed to be available at that location throughout
          the operation.
        </p>
<p>
          Asynchronous operations may utilise POSMs in a number of different ways:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              The operation doesn't require any POSMs. For example, the operation
              wraps an existing API that performs its own memory management, or is
              copying the long lived state into existing memory like a circular buffer.
            </li>
<li class="listitem">
              The operation uses a single, fixed-size POSM for as long as the operation
              is outstanding. For example, the operation stores some state in a linked
              list.
            </li>
<li class="listitem">
              The operation uses a single, runtime-sized POSM. For example, the operation
              stores a copy of a user-supplied buffer, or a runtime-sized array of
              iovec structures.
            </li>
<li class="listitem">
              The operation uses multiple POSMs concurrently. For example, a fixed
              size POSM for a linked list plus a runtime-sized POSM for a buffer.
            </li>
<li class="listitem">
              The operation uses multiple POSMs serially, which may vary in size.
            </li>
</ul></div>
<p>
          Associated allocators allow users to treat POSM optimisation as a cross-cutting
          concern to the composition of asynchronous operations. Furthermore, using
          allocators as the interface to obtain POSMs grant substantial flexibility
          to both the implementers and users of asynchronous operations:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              Users can ignore the allocator and accept whatever default strategy
              is employed by the application.
            </li>
<li class="listitem">
              Implementers can ignore the allocator, especially if the operation
              is not considered performance-sensitive.
            </li>
<li class="listitem">
              Users can co-locate POSMs for related asynchronous operations, for
              better locality of reference.
            </li>
<li class="listitem">
              For compositions that involve serial POSMs of different sizes, memory
              usage need only be as great as the currently extant POSM. For example,
              consider a composition that contains a short-lived operation that uses
              large POSMs (connection establishment and handshake) followed by a
              long-lived operation that uses small POSMs (transferring data to and
              from the peer).
            </li>
</ul></div>
<p>
          As noted previously, all resources must be released prior to calling the
          completion handler. This enables memory to be recycled for subsequent asynchronous
          operations within an agent. This allows applications with long-lived asynchronous
          agents to have no hot-path memory allocations, even though the user code
          is unaware of associated allocators.
        </p>
<h6>
<a name="boost_asio.overview.model.allocators.h0"></a>
          <span class="phrase"><a name="boost_asio.overview.model.allocators.see_also"></a></span><a class="link" href="allocators.html#boost_asio.overview.model.allocators.see_also">See
          Also</a>
        </h6>
<p>
          <a class="link" href="../core/allocation.html" title="Custom Memory Allocation">Custom Memory Allocation</a>.
        </p>
</div>
<div class="copyright-footer">Copyright © 2003-2024 Christopher M. Kohlhoff<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="executors.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../model.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="cancellation.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
